<html>
<head>
<title>
Conditional Random Field (CRF) Documentation
</title>
</head>
<body>
<a name="top"><H2 align="center"> Conditional Random Field (CRF) </H2></a>
<HR>
<table align="right">
<tbody>
<tr>
<td>
<a href="seqtask.html">Prev</a> | 
<a href="index.html">Home</a> |
<a href="features.html">Next</a>
</td></tr>
</tbody>
</table>
<br>
<H2>3. Various Interfaces</H2> 

<p align="justify">
	As described in the previous section, a user of this distribution would require
	to implement various interfaces defined in the <b>iitb.CRF</b> package of the code. 
	The most basic interfaces are the <a href="#DataIter">DataIter</a>
	and <a href="#DataSequence">DataSequence</a> interfaces; these are 
	mandatory for a user implement in order to use this package for an
	application. Optionally, a user may need to implement advanced interfaces
	like <a href="#Feature">Feature</a> and<a href="#FeatureGenerator"> FeatureGenerator</a>. Note that this section describes interfaces; for detailed API refer the <i>javadoc</i> for the package.
<p>

<h3> <a name="DataSequence">Public Interface DataSequence</a></h3>
		<p align="justify">
		A basic training/test instance would need to support the DataSequence interface.
		This interface defines a mechanism to access an instance of sequential data 
		encapsulated by the implementing class.  
		You would need to implement this interface for both the training as well as test instances, although you
		can have single class which can be used for both of them.
		The implemented class will encapsulate a token (x) sequence and the corresponding
		label (y) sequence.  
		The interface defines methods to access token (x) and label (y) at a particular position i.
		An x value in the sequence can be any object (a string or an object of a complex class); 
		CRF does not interpret this x value thus allowing it to be used in a large number of diverse applications. 
		A y value here is an integer. So, if your training set is labeled using any type (say a string label), then you would have to map those labels to integer labels and then create the object of DataSequence using the integer labels.
		Example implementations of the DataSequence interface are DCTrainRecord and DataRecord which can be 
		found in the Segment and MaxentClassifier modules respectively.
		</p>
		<h3><a name="DataIter">Public Interface DataIter</a></h3>
		<p align="justify">This is an iterator interface for data instances. 
		A class implementing this interface should encapsulate a set of training instances. 
		The object of this class will be passed to the training routine of the CRF package which will use the interface to iterate over the training set encapsulated in the object.
		Thus, each of your training instances should be read in an object of a class implementing the 
		<a href="#DataSequence">DataSequence</a> interface, and then an object of the class implementing 
		the DataIter interface would be used to iterate over the created <a href="#DataSequence">DataSequence</a> objects.
		</p>
		<h3><a name="Feature">Public Interface Feature</a></h3>
		<p align="justify">
		This class captures the basic attributes of a feature; an important one being
		the feature identifier. The FeatureIdentifier class describes an ID
		assigned to a feature. The abstract class <a href="features.html#FeatureTypes">FeatureTypes</a> (described in detail later) is a base class for creating new features. Whenever a feature is generated,
		it is assigned an ID by calling the setFeatureIdentifier() method of this class. 
		However, there is a notion of a global feature ID (will be referred to as index 
		from now on), which gives a
		unique identification to the features. The feature generator (see <a href="#FeatureGenerator">FeatureGenerator interface</a>) serves the purpose of assigning these indices which are
		contiguous IDs. If you are creating new features,
		you must ensure that unique IDs are assigned to the features generated by your application.
		Besides the FeatureIdentifier, another important attribute is the
		value of the feature, which basically gives a measure of the
		importance of the feature as assigned by the user.  An
		implementation of the Feature interface, namely the <a
		href="features.html#FeatureImpl">FeatureImpl</a> class, is present in
		the iitb.Model package; you can either use this implementation, or implement a new class from scratch.
		</p>
		<h3><a name="FeatureGenerator">Public Interface FeatureGenerator</a></h3>
		<p align="justify">
		FeatureGenerator interface is an aggregator over all the feature types. 
		The feature generator interface is used by iitb.CRF package to access all the features to be used for learning and inference. 
		Various methods in the interface are described below in brief.<BR>
		<ul>
		<li><i>numFeatures()</i><br> Number of features in the feature generator. As mentioned previously, a feature generator is an aggregator over all feature types (<a href="features.html#FeatureTypes">FeatureTypes</a>) classes, the number of features is sum of all features in all the feature type classes.
		<li><i>startScanFeaturesAt(DataSequence data, int pos)</i><br> This interface is used to instruct the FeatureGenerator to return all the features for label of the token at the position <i>pos</i> in the data sequence <i>data</i>.
		This method initiates generation of the features.
		<li><i>hasNext()</i><br> This method is used to check if there are any more features for the current scan intitaited in startScanFeaturesAt().
		<li><i>next()</i><br> Return the next feature for the current scan.
		</ul>
		
		There's a
		<a href="features.html#FeatureGenImpl">FeatureGenImpl</a> class provided in iitb.Model package that gives a sample implementation of this interface. 
		
		If you are a naive user of the model, you
		would mostly not need to implement this interface and use the
		<a href="features.html#FeatureGenImpl">FeatureGenImpl</a> class instead. 
		</p>

<a href="#top">top</a>
<!-- Draw a horizontal rule to separate above informative part form footer -->

<hr>
<table align="center">
<tbody>
<tr>
<td>
<a href="seqtask.html">Prev</a> | 
<a href="index.html">Home</a> |
<a href="features.html">Next</a>
</td></tr>
</tbody>
</table>

<hr>

<table align="center" width="100%">
<tbody>
<tr>
<td align="center"><B>
		Copyright &copy; 2004 KReSIT, IIT Bombay. All rights reserved </B>
</td>

</td>
</tr>
</tbody>
</table>
</body>
</html>
